<?php

namespace Kunfeng\Dify\Client;

use Kunfeng\Dify\Exception\DifyApiException;
use Kunfeng\Dify\Model\Datasets\CreateDatasetRequest;
use Kunfeng\Dify\Model\Datasets\Dataset;
use Kunfeng\Dify\Model\Datasets\DatasetListResponse;
use Kunfeng\Dify\Model\Datasets\CreateDocumentRequest;
use Kunfeng\Dify\Model\Datasets\Document;
use Kunfeng\Dify\Model\Datasets\DocumentListResponse;
use Kunfeng\Dify\Model\Datasets\RetrieveRequest;
use Kunfeng\Dify\Model\Datasets\RetrieveResponse;
use Kunfeng\Dify\Model\Datasets\Segment;
use Kunfeng\Dify\Model\Datasets\SegmentListResponse;
use Kunfeng\Dify\Model\Datasets\UpdateSegmentRequest;
use Kunfeng\Dify\Model\Common\SimpleResponse;

/**
 * Dify 知识库管理客户端接口
 */
interface DifyDatasetsClientInterface extends DifyBaseClientInterface
{
    /**
     * 创建知识库
     */
    public function createDataset(CreateDatasetRequest $request): Dataset;

    /**
     * 获取知识库列表
     */
    public function getDatasets(int $page = 1, int $limit = 20): DatasetListResponse;

    /**
     * 获取知识库详情
     */
    public function getDataset(string $datasetId): Dataset;

    /**
     * 更新知识库
     */
    public function updateDataset(string $datasetId, array $data): Dataset;

    /**
     * 删除知识库
     */
    public function deleteDataset(string $datasetId): SimpleResponse;

    /**
     * 创建文档
     */
    public function createDocument(string $datasetId, CreateDocumentRequest $request): Document;

    /**
     * 获取文档列表
     */
    public function getDocuments(string $datasetId, int $page = 1, int $limit = 20): DocumentListResponse;

    /**
     * 获取文档详情
     */
    public function getDocument(string $datasetId, string $documentId): Document;

    /**
     * 更新文档
     */
    public function updateDocument(string $datasetId, string $documentId, array $data): Document;

    /**
     * 删除文档
     */
    public function deleteDocument(string $datasetId, string $documentId): SimpleResponse;

    /**
     * 语义检索
     */
    public function retrieve(RetrieveRequest $request): RetrieveResponse;

    /**
     * 获取文档分段列表
     */
    public function getSegments(string $datasetId, string $documentId, ?int $page = null, ?int $limit = null): SegmentListResponse;

    /**
     * 获取分段详情
     */
    public function getSegment(string $datasetId, string $documentId, string $segmentId): Segment;

    /**
     * 更新分段
     */
    public function updateSegment(string $datasetId, string $documentId, string $segmentId, UpdateSegmentRequest $request): Segment;

    /**
     * 删除分段
     */
    public function deleteSegment(string $datasetId, string $documentId, string $segmentId): SimpleResponse;

    /**
     * 启用分段
     */
    public function enableSegment(string $datasetId, string $documentId, string $segmentId): SimpleResponse;

    /**
     * 禁用分段
     */
    public function disableSegment(string $datasetId, string $documentId, string $segmentId): SimpleResponse;
}
